[SILO-821] feat: add gitlab issue sync docs #388
Conversation
|
You have run out of free Bugbot PR reviews for this billing cycle. This will reset on January 20. To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughDocumentation updates: GitHub integration wording for unidirectional sync clarified as a mode and States row updated to indicate bidirectional capability; GitLab docs add a new "Sync issues" section detailing project-level issue sync and synced fields, but that section is duplicated in the file. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Linked to Plane Work Item(s) This comment was auto-generated by Plane |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI Agents
In @docs/integrations/gitlab.mdx:
- Around line 174-201: The images in the "Add project work item sync" section
use GitHub asset paths; replace the two occurrences of
"integrations/github/sync-project-github.webp" and
"integrations/github/sync-direction.webp" with the corresponding GitLab asset
paths (e.g., "integrations/gitlab/sync-project-gitlab.webp" and
"integrations/gitlab/sync-direction.webp") in docs/integrations/gitlab.mdx,
verify the GitLab screenshots exist at those locations, and update any related
alt/description text if needed to reflect GitLab UI.
- Around line 203-217: The images in the "Sync issues to Plane" GitLab section
reference GitHub assets; update the three image src paths so they point to the
GitLab assets instead of GitHub by replacing
`integrations/github/add-plane-label.webp`,
`integrations/github/synced-issue-from-github.webp`, and
`integrations/github/creates-plane-issue.webp` with the corresponding
`integrations/gitlab/...` filenames (e.g.,
`integrations/gitlab/add-plane-label.webp`,
`integrations/gitlab/synced-issue-from-gitlab.webp`,
`integrations/gitlab/creates-plane-issue.webp`) so the visuals match the GitLab
instructions.
- Around line 219-232: The images and alt text in the "Sync work items to
GitLab" block incorrectly reference GitHub; update the first image tag src from
"integrations/github/add-github-label.webp" to
"integrations/gitlab/add-gitlab-label.webp" and change its alt text from "Add
github label" to "Add gitlab label", and update the second image tag src from
"integrations/github/create-gitlab-issue.webp" to
"integrations/gitlab/create-gitlab-issue.webp" (ensure the alt text matches the
GitLab context, e.g., "Creates issue in GitLab").
🧹 Nitpick comments (1)
docs/integrations/gitlab.mdx (1)
224-224: Consider varying the phrasing for readability.The phrase "want to sync" is used similarly on line 208. While clear and correct, you could add variety:
🔎 Optional refinement
-1. In your Plane project, add the `gitlab` label to any work item you want to sync. +1. In your Plane project, add the `gitlab` label to any work item you wish to sync to GitLab.Based on static analysis hints.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/integrations/github.mdxdocs/integrations/gitlab.mdx
🧰 Additional context used
🪛 LanguageTool
docs/integrations/gitlab.mdx
[style] ~224-~224: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...the gitlab label to any work item you want to sync. 
🔇 Additional comments (4)
docs/integrations/github.mdx (2)
197-199: Documentation clarity improved.The updated warning text is more explicit about the overwrite behavior in unidirectional mode and provides clear guidance on enabling bidirectional sync. This improves user understanding of the sync modes.
209-209: This change is verified as intentional and accurate.The States field documentation has been consistently updated across both GitHub and GitLab integration docs to reflect bidirectional sync. Both integrations now document States as "Both ways" with the explanation "Updates in either platform reflect in the other." This aligns with the explicit feature documentation in lines 182-183, which states: "With bidirectional sync enabled, state changes in Plane work items will also update the GitHub issue status (open/closed)." The PR's focus on GitLab docs includes coordinating this documentation update across both integrations.
docs/integrations/gitlab.mdx (2)
170-266: Flag inconsistency with AI-generated summary.The AI summary mentions that the "Sync issues" section appears duplicated in the file, but only one instance is visible in the provided code. Please verify whether duplicate content exists elsewhere in the file.
233-266: Well-documented sync behavior and properties.The "How issue syncing works" and "What gets synced?" sections provide clear, comprehensive information about sync mechanics. The warning about unidirectional sync overwriting data is appropriately placed, and the property table clearly documents sync directions.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @docs/integrations/gitlab.mdx:
- Around line 154-182: The docs don’t explain the exact behavior of the trigger
labels, so add a short clarifying note under the GitLab sync sections explaining
whether the label names 'Plane' and 'gitlab' are case-sensitive, whether they
can be changed in settings, and whether the integration will auto-create labels
or requires them to pre-exist; specifically state the canonical forms ('Plane'
and 'gitlab'), the accepted case behavior (e.g., case-sensitive or normalized),
and whether admins can customize the trigger label or must create it manually in
GitLab for syncing to work.
- Around line 208-216: Update the table rows for "Mentions" and "Comments":
change "Mentioned users username" to the correct possessive plural "Mentioned
users' usernames"; and replace the vague "appears as posted by the Admin with
the username of the user who posted the comment" in the "Comments" row with a
clear statement that synced comments are attributed to the mapped Plane user
when a GitLab→Plane user mapping exists, otherwise they are posted by the
integration bot (include “with source attribution” if desired).
🧹 Nitpick comments (3)
docs/integrations/gitlab.mdx (3)
123-152: Clarify the exact navigation path + standardize “issue sync” vs “work item sync” terminology.
The section alternates between “project work item sync”, “Project Issue Sync”, and “sync issues”; tightening wording will reduce ambiguity about where this lives (Workspace settings vs Project settings) and what object is being synced (GitLab issues vs Plane work items).Proposed doc wording tightening
-### Add project work item sync +### Add project issue sync Once GitLab is connected to Plane, workspace admins can link GitLab Projects with Plane projects. -1. Navigate to the **Project Issue Sync** section under **Integrations**. +1. Navigate to **Workspace Settings → Integrations → GitLab → Project Issue Sync**. 2. Click the (+) button to create a new sync mapping.Also applies to: 154-182
141-150: Make sync direction naming explicit (GitLab → Plane / Plane → GitLab) and avoid repeating overwrite warnings.
Right now “Unidirectional” is described as GitLab→Plane in one place, then reiterated later; consider naming the direction inline and keeping a single canonical warning to reduce skimming errors.Also applies to: 202-204
266-266: Consider “merge request” vs “PR” wording consistency for GitLab pages.
This page generally uses “merge request”, but this line (and the section header) uses “PR”; if your docs style guide prefers “merge request” for GitLab, align it.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrations/gitlab.mdx
🧰 Additional context used
🪛 LanguageTool
docs/integrations/gitlab.mdx
[style] ~174-~174: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...the gitlab label to any work item you want to sync. 
🔇 Additional comments (1)
docs/integrations/gitlab.mdx (1)
121-218: No action needed. The "Sync issues" section is correctly structured with proper heading hierarchy—## Sync issues(H2) at line 121 and### Sync issues to Plane(H3) at line 154 are parent and child sections, not duplicates. The file organization is correct.
| ### Sync issues to Plane | ||
| After configuring project work item sync, you can link existing GitLab issues into your Plane project. | ||
|
|
||
| #### GitLab → Plane | ||
|
|
||
| 1. In your GitLab project, add the `Plane` label to any issue you want to sync. | ||
|
|
||
|  | ||
| 2. The issue will automatically be created as a work item in the linked Plane project. | ||
| 3. Plane posts a comment on the GitLab issue with a link to the newly created work item, confirming the connection. | ||
|
|
||
| 4. The work item in Plane will include a link back to the original GitLab issue. | ||
|
|
||
|  | ||
|
|
||
| ### Sync work items to GitLab | ||
| If you have existing work items in Plane that you want to sync to GitLab, you can do so using labels. | ||
|
|
||
| #### Plane → GitLab | ||
|
|
||
| 1. In your Plane project, add the `gitlab` label to any work item you want to sync. | ||
|
|
||
|  | ||
| 2. A new issue will automatically be created in the linked GitLab project. | ||
|
|
||
|  | ||
| 3. The GitLab issue will be linked back to the Plane work item. | ||
| 4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional). | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, run the provided consistency check
rg -nP '`Plane`|`gitlab`|label' docs/integrations/gitlab.mdxRepository: makeplane/docs
Length of output: 822
🏁 Script executed:
#!/bin/bash
# Search for GitLab integration label handling in the codebase
# Look for files related to GitLab sync implementation
fd -e py -e ts -e tsx -e js -e jsx | xargs rg -l "gitlab.*label|label.*gitlab" -i | head -20Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
#!/bin/bash
# Search specifically for where these labels are validated/checked
rg -i "plane.*label|gitlab.*label" --type py --type ts --type tsx --type js --type jsx -A 5 -B 5 | head -100Repository: makeplane/docs
Length of output: 85
🏁 Script executed:
#!/bin/bash
# Search for GitLab sync implementation - label handling in the main plane repo
# Look for files that handle GitLab issue/label sync
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" \) | xargs rg -l "gitlab.*sync|label.*sync" -i 2>/dev/null | grep -E "(gitlab|integration)" | head -20Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
#!/bin/bash
# Search for where "Plane" label is checked/validated
rg -i "plane.*label\"|label.*plane\"|\"Plane\"" --type py --type js -A 3 -B 3 2>/dev/null | head -150Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
#!/bin/bash
# Search for GitLab label trigger constants or configuration
rg -E "(PLANE_LABEL|GITLAB_LABEL|trigger.*label)" --type py --type js -i -A 2 -B 2 2>/dev/nullRepository: makeplane/docs
Length of output: 40
🏁 Script executed:
#!/bin/bash
# Search entire docs repo for mentions of case-sensitivity, customization, or pre-existing labels
rg -i "case.?sensitive|customiz|pre.?exist|must exist|required" docs/ -A 2 -B 2Repository: makeplane/docs
Length of output: 36018
🏁 Script executed:
#!/bin/bash
# Look at the full GitLab integration doc to see if there's more context
head -n 250 docs/integrations/gitlab.mdx | tail -n 50Repository: makeplane/docs
Length of output: 4416
🏁 Script executed:
#!/bin/bash
# Check if there are other similar integration docs that explain label behavior
ls -la docs/integrations/Repository: makeplane/docs
Length of output: 544
🏁 Script executed:
#!/bin/bash
# Search for any configuration or FAQ sections about labels
rg -i "label.*behavior|label.*work|sync.*label|how.*label" docs/ --type mdx -A 3Repository: makeplane/docs
Length of output: 85
Document the behavior of trigger labels (Plane and gitlab) — docs don't explain if they're case-sensitive or customizable.
The documentation presents these as required "magic" labels but doesn't clarify: whether they're case-sensitive (the inconsistent casing Plane vs gitlab suggests they are), whether they can be customized in settings, or whether they must pre-exist. Users will fail silently if they use Gitlab or plane instead. Add a note explaining exact label requirements, case-sensitivity, and whether labels can be customized or auto-created.
🧰 Tools
🪛 LanguageTool
[style] ~174-~174: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...the gitlab label to any work item you want to sync. 
🤖 Prompt for AI Agents
In @docs/integrations/gitlab.mdx around lines 154 - 182, The docs don’t explain
the exact behavior of the trigger labels, so add a short clarifying note under
the GitLab sync sections explaining whether the label names 'Plane' and 'gitlab'
are case-sensitive, whether they can be changed in settings, and whether the
integration will auto-create labels or requires them to pre-exist; specifically
state the canonical forms ('Plane' and 'gitlab'), the accepted case behavior
(e.g., case-sensitive or normalized), and whether admins can customize the
trigger label or must create it manually in GitLab for syncing to work.
| | Property | Sync direction | Notes | | ||
| | -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Title | Both ways | Updates in either platform reflect in the other. | | ||
| | Description | Both ways | Content remains consistent between Plane and GitLab. | | ||
| | Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). | | ||
| | States | Both ways | Updates in either platform reflect in the other. | | ||
| | Comments | Both ways | Comments sync between platforms with source attribution. The comment appears as posted by the Admin with the username of the user who posted the comment. | ||
| | Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. | | ||
| | Issue links | GitLab → Plane | Any issue references in GitLab descriptions or comments will be displayed in Plane with a direct link to the issue including the project name and owner. | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, check the file exists and view the relevant section
head -220 docs/integrations/gitlab.mdx | tail -30Repository: makeplane/docs
Length of output: 3692
🏁 Script executed:
# Also search for any other mentions of comment attribution behavior in the docs
rg "comment.*admin\|admin.*comment" -i docs/integrations/gitlab.mdx -A 2 -B 2Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
# Search for implementation details about GitLab integration and comment syncing
fd -e py -e ts -e js -e tsx | xargs rg -l "gitlab.*comment\|comment.*gitlab" -i | head -5Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
# Search for GitLab integration implementation in the codebase
fd -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) | xargs rg -l "gitlab" -i | grep -E "(integr|sync)" | head -10Repository: makeplane/docs
Length of output: 302
🏁 Script executed:
# Broader search for comment sync or attribution logic
rg "comment.*sync\|sync.*comment" -i -A 3 -B 1 --max-count 10 | head -50Repository: makeplane/docs
Length of output: 40
🏁 Script executed:
# Look for any integration-related files
fd -type d -name "*integr*" -o -name "*gitlab*"Repository: makeplane/docs
Length of output: 228
🌐 Web query:
Plane GitLab integration comment attribution how comments are displayed
💡 Result:
Short answer: Plane syncs comments with GitLab and shows an attribution for the source; comments created by GitLab (e.g., MR/issue comments or the Plane backlink comment on an MR) are displayed in Plane with their source noted, and Plane will attribute comments to the mapped Plane user when a GitLab account is mapped — otherwise the comment appears as coming from the integration/bot. You can also create/sync comments via Plane’s API using external_source/external_id fields so imported comments retain external attribution.
Sources:
- Plane GitLab integration docs (integration behavior, PR backlinks and Plane comments on MRs). [1]
- Plane GitHub integration docs (comments sync both ways with source attribution; unmapped users show as the platform bot). [2]
- Plane API comment endpoints (comment_html, external_source, external_id fields used when creating/syncing comments). [3]
References:
[1] Plane — Integrate GitLab.
[2] Plane — Integrate GitHub (comments sync & attribution).
[3] Plane API — Create work item comment (external_source / external_id).
🌐 Web query:
Plane project sync GitLab comments admin attribution
💡 Result:
Short answer: Plane syncs GitLab comments and posts its own “Plane App” comment when work items/PRs are linked; comments are attributed to the original GitLab user only if that GitLab account is mapped to a Plane workspace user — otherwise the comment will be shown as coming from the integration/bot (or the Plane/GitHub bot example). To avoid comments showing as an admin/bot, map users or connect personal accounts so Plane can attribute comments to the correct user. [1][2]
What to do (concise):
- Connect GitLab to Plane (workspace Integrations → GitLab) and add the GitLab project connection. This enables webhooks and comment/PR sync. [2]
- Ensure each GitLab commenter has a matching Plane workspace account (or have them “Connect personal GitLab account” in Plane) so Plane can map GitLab identities to Plane users. If a GitLab user isn’t mapped, Plane will post/sync comments as the integration/bot. [1][2]
- If you must use a shared admin/service account for the integration, expect comments created by that account (or unmapped users) to be attributed to the integration/admin in Plane; instead prefer per-user OAuth connections or invite users to Plane and map identities. [1][2]
- If you run a self-managed GitLab and need Org-level admin actions, use the GitLab Admin area to manage user accounts and confirm the accounts exist and can be matched to Plane users. [3]
Sources:
- Plane — GitLab integration (setup, PR/work-item linking, comment/backlink behavior). [1][2]
- GitLab — Admin area docs (managing self-hosted users/projects). [3]
References:
[1] Plane — “What gets synced?” / comment attribution notes.
[2] Plane — Integrate with GitLab (connect org/project, PR automation, work item backlinks).
[3] GitLab — Admin area (self‑managed user/project administration).
Fix grammar/clarity issues and correct the misleading comment attribution statement.
The "Mentioned users' usernames" needs proper possessive plural form. More importantly, the Comments row incorrectly claims "appears as posted by the Admin"—in reality, synced comments are attributed to the mapped Plane user if a GitLab-to-Plane user mapping exists; otherwise they appear as coming from the integration bot. This should be clarified rather than vague.
Suggested revisions
-| Comments | Both ways | Comments sync between platforms with source attribution. The comment appears as posted by the Admin with the username of the user who posted the comment.
-| Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. |
+| Comments | Both ways | Comments sync between platforms with source attribution. Comments are attributed to the mapped Plane user; if no mapping exists, they appear as posted by the integration bot. |
+| Mentions | Both ways | Mentioned users' usernames are displayed in Plane and in the GitLab issue. |🤖 Prompt for AI Agents
In @docs/integrations/gitlab.mdx around lines 208 - 216, Update the table rows
for "Mentions" and "Comments": change "Mentioned users username" to the correct
possessive plural "Mentioned users' usernames"; and replace the vague "appears
as posted by the Admin with the username of the user who posted the comment" in
the "Comments" row with a clear statement that synced comments are attributed to
the mapped Plane user when a GitLab→Plane user mapping exists, otherwise they
are posted by the integration bot (include “with source attribution” if
desired).
Description
Type of Change
Screenshots and Media (if applicable)
Test Scenarios
References
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.